AmigaWin Launcher 1.4 by Lord_Santa using Claude Opus 5.5 (Medium)
=====================

Drag an Amiga game onto "AmigaWin Launcher.exe" (or onto its window) and press START.

Runs on Windows XP SP3 (32-bit) up to Windows 11. Needs the .NET Framework 4.0 or newer:
already part of Windows 8, 10 and 11; on XP, Vista and 7 install ".NET Framework 4.0"
(XP) or 4.8 (Vista SP2 / 7) from Microsoft first.

Accepted: .zip (with anything below inside, nested zips too), .adf, .adz, .dms, .ipf,
.hdf, .lha/.lzh/.lzx WHDLoad archives, and plain WHDLoad game folders.

Portable: runs from any drive
-----------------------------
* Copy the whole AmigaWin Launcher folder anywhere - another drive, a USB stick, another
  PC - and it keeps working: games, saves, options, artwork, manuals and music come along.
* Everything lives inside its own folder: Games (put games here), Library (per-game
  saves, options, artwork, manuals), Music, Tools (WinUAE, WHDLoad, music player) and
  AmigaWinLauncher.settings.json. Paths inside the folder are stored relative to it, and
  paths elsewhere on the same drive without the drive letter, so a changed drive letter
  does not matter.
* The WinUAE it downloads keeps its own settings in a winuae.ini next to it instead of
  the Windows registry, so nothing is left behind on the PC.
* On first start it only looks for games inside its own folder (it will not pick up a PC
  "Games" folder elsewhere on the drive). Add other folders with "+ Add folder".

Your game library
-----------------
* The left column lists every game in your library folders (found automatically on first
  run, e.g. a WHDLoad "GAMES" folder next to WinUAE; add more with "+ Add folder" or by
  dropping a folder of games onto the window). Sub-folders are included.
* Type anywhere to search (title, year, publisher, "aga", "whdload"). Arrow keys move,
  Enter or double-click plays. Right-click a game for more.
* Files with the same title are merged into one entry; the versions show under "Version".
* Zip files are peeked into, so non-Amiga zips in the same folder are ignored.

Saving your progress (5 slots per game)
---------------------------------------
* However you leave a game - Ctrl+F11, Alt+F4, closing the window, STOP, or the game's
  WHDLoad quit key - the emulator saves the exact moment you left. The launcher then asks
  "Save your progress?" and shows 5 slots with pictures: click one to keep it, or
  "Don't save".
* Under "Continue" on each game's page, click a slot to pick up exactly where you left off.
  START always begins a new game. Right-click a slot to delete it.
* Saves live in Library\<game>\states (slot1-5.uss + a picture each).

Manuals, code wheels and readme files
-------------------------------------
* When a game is picked the first time, its manual (and code wheel / hint book / reference
  card, when there is one) is downloaded from the OpenRetro game database - the same page
  the artwork comes from - page by page, and bound into a PDF.
* Readme, manual and AmigaGuide files that came inside the game itself are listed too.
* They appear as buttons under the artwork ("Docs:"). The viewer turns pages with the
  arrow keys, Page Up/Down or the mouse wheel; "Open PDF" opens the PDF in your own reader
  (to print a code wheel, for example). Files live in Library\_art\<game>\docs.
* Switch this off in Settings. Not every game has a scanned manual online.

Music
-----
* While a game is selected, the launcher plays music. First the game's own soundtrack:
  tracker tunes found inside the game's files, inside the files on its disks, on
  trackloader disks and inside PowerPacker- and Rob Northen (RNC)-crunched files.
* Then your own music: put tracker tunes in the "Music" folder next to the launcher
  (sub-folders are fine; another folder can be chosen in Settings). Both "song.mod" and
  Amiga-style "mod.song" names work. When a game has no music of its own, a tune from
  your Music folder plays instead, and it keeps playing while you browse other games.
* Your own soundtrack for one game: make a folder inside Music named after the game
  (for example Music/Turrican 2/) and put its tunes there. They play first whenever that
  game is selected.
* The buttons above the artwork: Back, Play, Pause, Forward and Stop. When a tune ends,
  the next one starts. "Music: on/off" at the top decides whether music starts by itself.
  The music stops when a game starts and comes back when you return.
* Music player: without it the launcher plays ProTracker MODs itself. The free music
  player libopenmpt (BSD licence, lib.openmpt.org) adds about 70 formats: OctaMED/MED,
  Future Composer, DigiBooster, Oktalyzer, XM, S3M, IT and more. Get it with
  "Get the music player" under the music buttons, or in Settings -> "Download tools...".
  On Windows XP / Vista the Setup window lists the file to fetch yourself (the "retro
  winxp" build) and "I have libopenmpt..." installs it. It lives in Tools\MusicPlayer.
* Many games use their own music players (Rob Hubbard, David Whittaker, TFMX, Maxis
  and so on); those cannot be played outside the game, so such games use your Music folder.

Get games
---------
* "Get games" at the top opens a menu of websites you add yourself (Edit sites...). They
  open in your normal browser.
* Amiga games you download into your Downloads folder (zip, adf, adz, dms, lha, hdf...)
  are added to My Games automatically, with artwork. Zips without Amiga content are ignored.
  The watched folder can be changed or switched off in Settings.

Making a release
----------------
Run make-release.ps1: it builds release\AmigaWin Launcher <version>\ and a zip containing
only the program and this README - no settings, library, tools, ROMs or personal paths.
Every path is detected on the user's own PC at first start.

Artwork
-------
* Box art and 4 screenshots per game are downloaded from the OpenRetro game database
  (openretro.org) the first time a game is shown, or for the whole list with "Get all art".
  They are cached in Library\_art, so each game is fetched once.
* Click any picture to view it full screen (arrow keys / mouse wheel to browse).
* Wrong or missing pictures? "Find the right game..." under the artwork lets you search
  and pick the correct entry (or choose "No artwork").
* Downloads can be switched off in Settings.

What it does on its own
-----------------------
* Recognises the game: TOSEC/scene file names (title, year, publisher, disk N of M,
  AGA/ECS/NTSC tags), WHDLoad slave headers (real game name, AGA flag, kickstart needed),
  and the AmigaDOS volume names stored on each disk.
* Picks the cleanest release when a zip holds several ([b] bad dumps, [a] alternates and
  [t] trainers are ranked lower but stay selectable under "Version"). A trainer set that only
  has a Disk 1 borrows Disks 2..N from the original release.
* Picks the machine: A500 + KS1.3 for OCS games, A500+/A600 when tagged, A1200 + KS3.1
  for AGA, and A1200 with 8 MB fast RAM for WHDLoad / hard-disk games.
* Modern defaults: borderless fullscreen, 4:3 with borders trimmed, sharp pixels,
  70% stereo separation, gamepad if one is plugged in (else arrow keys + Right Ctrl),
  faster loading for AmigaDOS disks.

The best setup for each game
----------------------------
* WHDLoad games are looked up in the WHDLoad hardware database (11,000+ installs, kept
  up to date by the Amiga community and used by the Amiberry emulator): AGA or not,
  NTSC, mouse or joystick, CD32 pad (all buttons on your gamepad), fast CPU / JIT,
  immediate blitter, exact CPU timing, extra memory. It is downloaded once and refreshed
  monthly (Library\_db).
* Floppy games are looked up on OpenRetro (FS-UAE's game database, the same page the
  artwork comes from). Your exact version is recognised by the checksums of its disk
  images, and its settings are used: Amiga model, chip memory, NTSC, mouse-only games,
  how many floppy drives it tolerates, and known problems.
* The game itself is read too (WHDLoad header: AGA, 68020, memory needs).
* The Setup box shows where the setup came from. Only options left on "Auto" follow it;
  anything you choose yourself wins.
* "Not working? Try another setup" (under Setup) steps through the usual fixes, one per
  click: exact timing, fastest, NTSC, Amiga 600 / Kickstart 2, and back to automatic.
* Accuracy (in Options): Auto, "Most compatible" (exact timing) or "Fastest".
* The databases need a secure internet connection (not available on Windows XP/Vista);
  without them the launcher's own detection is used, as before.

Cheats and game options
-----------------------
* Many WHDLoad installs build in their own options: infinite lives, level select,
  difficulty, "use CD32 controls" and so on. They appear under Options, below
  "The game's own options (WHDLoad)", and are passed to the game when it starts.

Gamepad
-------
* The launcher itself works with just a controller (a hint line at the bottom shows the
  buttons when a pad is connected):
    d-pad / left stick = move through the games      LB / RB = a page at a time
    A or Start         = play                         X = continue from the newest save
    Y                  = pictures full screen         Back = music play / pause
    Left / Right       = other version of the game    B = clear the search / close
  In the pictures, the manual viewer and the "Save your progress?" window the d-pad moves,
  A confirms and B goes back. When a game ends the launcher comes back to the front by
  itself, so you never need the mouse.
* Shortcuts while playing (Settings can switch them off):
    hold Back + Start  = back to the launcher (with the usual "save your progress?")
    Back + LB          = quick save
    Back + RB          = quick load
* Pad buttons in games: A is fire, the d-pad and stick move the joystick, and by default
  B = joystick up, which is "jump" in most Amiga games. For about 400 games the WHDLoad
  database adds the game's own layout (e.g. Start = P for pause, X = Space).
  Options -> "Gamepad buttons: Change..." shows every button for the selected game and
  lets you pick what each one does (fire, 2nd fire, joystick up/down/left/right, Space,
  Return, Esc, P, Help, F1-F10, cursor keys, letters, numbers ...). The defaults for all
  games are under Settings -> "Pad buttons...". Games played with a CD32 pad keep the
  pad's own buttons. Keys are only sent while the emulator window is in front.
* Two players: for two-player joystick games the mouse port gets player 2's joystick -
  a second gamepad if one is plugged in, otherwise the keyboard. "Player 2" under Options
  changes it (Mouse / Second gamepad / Keyboard).

Quick save and quick load
-------------------------
* While playing: Ctrl+Shift+F5 = quick save, Ctrl+Shift+F9 = quick load (or Back+LB /
  Back+RB on the pad). WinUAE can only write a complete snapshot as it closes, so a quick
  save closes the emulator, keeps the snapshot and starts the game again from it - a pause
  of a few seconds, then you carry on. "Quick save" under Continue starts from it too.

Disks and swapping
------------------
* WHDLoad games never need swapping. Press the game's quit key (shown in the launcher)
  and you return to the launcher automatically.
* Floppy games: every game disk is inserted at once in DF0-DF3 (up to 4). AmigaDOS
  games find their disks by name without asking. A blank, formatted save disk is created
  and inserted too (kept per game in Library\<game>\Save disk.adf).
* If a game insists on DF0 ("insert disk 2"), press Ctrl+Shift+2 (Ctrl+Shift+<number> =
  that row in the disk list, Ctrl+Shift+0 = next disk). A banner confirms the swap.
  These keys go through WinUAE's control pipe and are never seen by the Amiga.
  Note: the launcher cannot see a game's on-screen "insert disk" prompt, so for games
  with more than 4 disks, or games that only read DF0, you press the key.
* Ctrl+F11 closes the emulator, F12 opens WinUAE's own menu.

Where things live
-----------------
* Library\       one folder per game: unpacked files, its config (game.uae), the save
                 disk and your last options. Disk saves persist between sessions.
* AmigaWinLauncher.settings.json   paths to WinUAE, Kickstart ROMs and the Workbench
                 folder (auto-detected; change them under Settings).

First start / downloads
-----------------------
If WinUAE or WHDLoad is missing, a Setup window offers to download them (free) into the
Tools folder next to the launcher. It detects your Windows (you can correct it) and picks
the WinUAE version that runs on it:
* Windows XP / Vista: WinUAE 4.2.1 (32-bit), the last version for XP
* Windows 7 and later: the newest WinUAE, 64-bit on 64-bit Windows
On Windows XP and Vista, or when there is no secure internet connection, nothing is
downloaded automatically: the Setup window lists the exact files and plain-http links
instead ("Copy instructions" puts them on the clipboard), so you can fetch them on any
computer and pick them with "I have WinUAE...", "I have WHDLoad..." and
"I have skick346.lha...". The same list appears if an automatic download fails.
Artwork and manuals need a secure connection too, so they are not available on XP/Vista.
* WinUAE      - from winuae.net (older versions from its download archive)
* Music player - libopenmpt from lib.openmpt.org (optional)
* WHDLoad     - whdload.de (freeware since version 18.0)
* RTB files   - Aminet util/boot/skick346.lha (kickstart relocation tables for WHDLoad)
It can be reopened any time from Settings -> "Download tools...".

What can NOT be downloaded: Kickstart ROMs and Workbench are still copyrighted. Point
Settings at your own ROM folder (e.g. from Amiga Forever or your own Amiga). Without ROMs,
WinUAE's free AROS replacement is used for floppy games; WHDLoad games need a real
Kickstart 2.0+ ROM. A Workbench folder is optional: without one, WHDLoad games boot from
a small launcher-made boot drive (Library\_boot) that uses the downloaded WHDLoad and
kickstart images copied from your ROMs under the names WHDLoad expects.

.lha WHDLoad archives are unpacked by the launcher itself (LHA -lh0/5/6/7), so they run
from a normal folder and can save.

Diagnostics: "AmigaWin Launcher.exe" --scan <game.zip> <report.txt> writes what was
detected and the exact WinUAE config it would use.

Source: src\ (C# WinForms for .NET Framework 4.0, built with the .NET SDK). Rebuild with:
  dotnet build src -c Release      (result: src\bin\Release\net40\AmigaWin Launcher.exe)
